---

Abstract Data Types

The 3D Metafile file format defines the following seven abstract data types: object type, size, bitfield, enumerated type, file pointer, string, and raw data. File pointers are discussed in another section. The other six abstract data types are discussed in this section.

Object Type

Every metafile object has a type. In a text file, an object type is expressed by a character string, such as Polygon. In a binary file, an object type is expressed by a 4-byte code, such as plyg. In both text and binary files, every object specification begins with an object type.

The metafile file format allows you to introduce new types of custom objects. Whenever you do so, you must first declare and register a new type tag for custom objects of that type. The manner in which new type tags may be declared and registered is explained in the section "Types" on page 1-42.

Size

All metafile objects are padded to 4-byte boundaries; thus, the size of an object is always a multiple of 4.

In a text file, object specifications are delimited by parentheses, as shown in the following example:

 Polygon (         # object type
  3        # number of vertices
  0 0 0        # first vertex
  1 0 0        # second vertex
  0 1 0        # third vertex
 )

The type Polygon and the parentheses are ignored when the size of the polygon is computed. Only the sizes of the values in the fields of the structure are taken into account. This polygon is a structure having two fields. The value in the first field is an unsigned 32-bit integer, and the value in the second field is an array of three three-dimensional points (the array tag and encapsulating brackets are omitted in the metafile specification). The size of an unsigned 32-bit integer is 4 bytes, and the size of a three-dimensional point is 12 bytes, so the size of the above polygon is 40 bytes.

In a binary file, an object specification must always include a line that indicates the size of that object. The above polygon would be specified in a binary file as follows:

 00: 706C6967     plyg    # object type
 04: 00000028     40    # object size
 08: 00000003     3    # number of vertices
 0A: 00000000     0.0    # x coordinate of first vertex
 10: 00000000     0.0    # y coordinate of first vertex
 14: 00000000     0.0    # z coordinate of first vertex
 18: 3F800000     1.0    # x coordinate of second vertex
 .
 .
 .

Indications of object type and object size do not contribute to the size of an object. Thus, the size of the above polygon is 40 bytes, not 44 or 48.

An object may be of size 0. In a text file, an object of size 0 is described by a tag followed by a pair of empty parentheses. For example, AttributeSet ( ) specifies an object of size 0. Some objects have a defined default specification. If such an object is represented as being of size 0, it is understood that the default specification is intended.

IMPORTANT

With the exception of geometric objects, default object specifications are not written to a file. ·

Bitfields and Enumerated Types

Bitfields and enumerated types establish associations between unsigned integers and ASCII text strings. The names of bitfields and enumerated types may include either text characters or digits, but do not include blank spaces or punctuation marks. In binary files, bitfields and enumerated types are represented by unsigned 32-bit integers such as (in hexadecimal) 0x00000001, 0x0000000E. The strophe symbol (|) is used to catenate bits both in text and binary files.

Strings

In a text file, a string is a sequence of ASCII text symbols enclosed in double quotation marks.

Only the following escape sequences may occur in a text file string:

\n

newline

\r

carriage return

\t

horizontal tab

\v

vertical tab

\\

backslash

\'

single quotation mark

\"

double quotation mark

In a binary file, a string is represented by a string of zero-terminated padded characters. The size of a string in a binary file is determined as follows:

 len = strlen(string);
 pad = (len + 1) % 4
 size = len + ((pad > 0) ? 4 - pad : 0)

Raw Data

Raw data are used to store information that is platform dependent or is inherently nonalphanumeric.

In a text file, raw data are stored as hexadecimal strings prefixed by the characters '0x'. Strings of raw data are not padded in text files. However, your application may pad them if you wish.

In a binary file, raw data are stored as sequences of bytes, padded to a 4-byte boundary. The size of raw data is computed as follows:

 pad = rawDataSize % 4
 size = rawDataSize + (pad > 0 ? 4 - pad : 0)

File Pointers

Description

A metafile file pointer indicates the location of another object in that metafile, to which it points. A file pointer and the object to which it points (called the target object) must occur in the same file. A target object may occur before or after an associated file pointer in a metafile. A file pointer may fail to have a target object; such a file pointer is null. File pointers may occur both in ASCII text metafiles and in binary metafiles. A file pointer is neither declared nor initialized; it is identified as such by the positions in which it may appear and (in a text file) by the type of expression used to represent it.

In a binary metafile, a file pointer is represented by an unsigned 64-bit integer that reports the address or location of its target object in the metafile. A generator of a binary metafile must determine the number of bytes by which a target object is offset from the end of the header in order to write the correct value of a pointer to that object and must update that file pointer whenever any new objects are inserted between the positions occupied by the pointer and its target object in the metafile.

Note

A file pointer is offset relative to the end of the header of the file in which it occurs, not relative to the beginning of that file. ·

In an ASCII text metafile, a file pointer is represented by a character string composed of at least two characters, the last of which is a right angle bracket (>). Thus p> and Arrow> are file pointers; p, >, and Arrow are not. In a text file, the target object of a file pointer must bear a label corresponding to that file pointer. The label corresponding to a file pointer is the result of omitting the final right angle bracket from the string representing that file pointer. For example, the label corresponding to string> is string. Such a label is always followed immediately by a colon, then by the target object: string: targetobject. Each file pointer may correspond to at most one label, and each label may correspond to at most one file pointer. A metafile should not contain a label that does not correspond to a file pointer, but the presence of such a label does not invalidate a metafile.

Two types of file pointers may occur in a metafile, corresponding to two types of target object a file pointer may have. The target object of a file pointer of the first type is a table of contents; such a file pointer is meant to indicate the location of a table of contents and serves no other purpose. (A file pointer of this type must occur in the fourth field of each header. A file pointer of this type must also occur in the first field of each table of contents; this pointer points to the location of the next subsequent table of contents, if one exists. A file pointer of this type may occur in no other position.)

The target object of a file pointer of the second type must be either an object of type shared or a container the root object (that is, the first object) of which is of type shared. The root object of a container may not be the target object of a file pointer. The purpose of a file pointer of this type is to enable the metafile writer to make repeated reference to a target object without repeating that object's definition. (A file pointer of this type may occur only in the second field of a table of contents entry; thus, a metafile that contains file pointers of this type must include at least one table of contents.) The way in which repeated reference to an object is accomplished through the use of file pointers of this type is explained in the next paragraph.

An application may also permit a user to make reference in one context to an object specified or created in another context, in order to facilitate the construction of complex objects from component objects and to permit the user to place the same object in several scenes or at several positions in the same scene without having to specify or create that object several times. In a metafile, reference to objects defined elsewhere is accomplished in a manner involving several components: a file pointer, a target object, an integer, an entry in a table of contents, and a special metafile object called a reference object. (In a text file, the label corresponding to a file pointer must also be present.) The object to be referenced at some other position must be the target object of a file pointer. That file pointer must appear together with an appropriately chosen integer in an entry in a table of contents located in the file containing the target object. (If that file contains no table of contents, then a table of contents must be created.) The integer thus associated with that file pointer must be entered in the field of a reference object, one occurrence of which must be placed at each position at which the target object is to be referenced.

The target object, file pointer, and table of contents must all occur in the same file. The reference object associated with a target object may occur in the same file or in another file. A reference in a file to a target object located in the same file is termed internal; a reference in a file to a target object located in a different file is termed external. In the latter case, the reference object must also have a child object that indicates the location of the home file of the target object. A lengthy specification may be modularized and spread across several files through the use of external references. See the sections "Tables of Contents" on page 1-32 and "Reference Objects" on page 1-37 for further information about these objects.

There may be at most one file pointer to any target object; thus, once an integer has been associated with a pointer to a target object in a table of contents entry, that integer is the only integer that may be used (in any file) to reference that target object. (A file pointer of this type that is not associated with a reference object is legal, but serves no purpose.)

Clearly, a metafile reader must be programmed to recognize and to respond appropriately to reference objects, tables of contents, and file pointers and not to confuse them with other types of objects. As noted, a metafile may contain file pointers and reference objects that are idle. A metafile reader cannot determine whether a file pointer or reference object is idle by inspection of that object; thus, an efficient reader should search out these special metafile objects prior to reading the body of the metafile.

Examples

Here are some examples of legal uses of file pointers in an ASCII text metafile:

3DMetafile (         # header
 1 0
 Normal
 toc>        # pointer to table of contents
)
.
.
.
Linus: Line ( 0 0 0  1 0 0)         # label and target object
.
.
.
Translate ( 0 1 0 )
Reference ( 1 )         # reference object
.
.
.
toc: Table of Contents (         # label and target object
  nextTOC>       # pointer to next table of contents
           (may be idle)
...
  1 Linus>      # table of contents entry, including
        file pointer and integer occurring in
        related reference object
.
.
.
)

The file pointer Linus> is used to place its target object within the scope of a translation; thus, it adds to the model the image of the original line under a translation.

arrow: 
BeginGroup ( DisplayGroup ( ) )
 arrowTip: 
 BeginGroup ( DisplayGroup ( ) )
  Translate ( ... )
  Scale ( ... )
  Container (
   cone ( ... )
   arrowColor:
   Container (
    AttributeSet ( )
    DiffuseColor ( ... )
   )
  )
 EndGroup ( )
 arrowShaft:
 BeginGroup ( DisplayGroup ( ) )
  Scale ( ... )
  Container (
   Cylinder ( ... )
   Reference ( 1 )
  )
 EndGroup ( )
EndGroup ( )
. . .
toc: 
TableOfContents ( 
 ... 
 1 arrowColor> 2 arrowTip> 3 arrowShaft> 4 arrow>)

The complex object specified in this example is an arrow-shaped object having a cylindrical shaft and a conical tip, both of which are the same color. The components of the arrow are labeled and associated with file pointers so that they may be referenced elsewhere if desired. The object labeled arrowColor occurs within the definition of the object labeled arrowTip. The reference object Reference ( 1 ) is used to include that object in the specification of the arrow's shaft, in order to assign to the arrow's shaft the color already assigned to its tip. See the sections "Display Groups" on page 1-194 and "Containers" on page 1-44 for explanations of how these objects may be used to form complex structured objects.

---

3D Metafile Reference

© Apple Computer, Inc.